package de.androidbuch.amando.services;

import java.util.List;
import de.androidbuch.amando.common.GpsDataParcelable;
import de.androidbuch.amando.services.IServiceCallback;


/**
 * Interface für die öffentlichen Methoden des GeoPositionsService.
 * 
 * Der Zugriff auf die Methoden wird über einen Binder realisiert, der Teil
 * der Service-Implementierung ist.
 * 
 * @author Arno Becker, 2010 visionera gmbh
 * 
 */
interface IGeoPositionsServiceRemote {
  
  /** Liefert die letzte bekannte eigene Position. */
  GpsDataParcelable getGpsData();
  
  /** 
   * Sendet die zuletzt bekannte eigene Position per SMS an einen
   * Empfänger mit der Mobilnummer 'empfaengerNr'. 
   * 
   * Falls 'positionAktualisieren' true ist, wird die Position 
   * zusätzlich an den Amando-Server geschickt. Der Empfänger der
   * SMS (der Client) ist nun berechtigt, die Positionsänderungen
   * des SMS-Senders nachzuverfolgen. Daher werden Positionsänderungen
   * jeweils an den Amando-Server geschickt. 
   * 
   * Der @see{GeoPositionsServiceImpl} implementiert einen LocationListener.
   * Dieser schickt bei Ortsveränderungen die aktuelle Position an den
   * Amando-Server, der sie an den Client weiterleitet (allerdings nur, wenn
   * 'positionAktualisieren' true ist).
   * 
   * @param empfaengerNr Mobilnummern der Empfänger
   * @param stichwort ein Stichwort, was an die Empfänger geschickt wird
   * @param positionAktualisieren Empfänger darf Positionsänderungen des 
   *     SMS-Senders nachverfolgen.
   */
  void sendeGeoPosition(in List<String> empfaengerMobilnummern,
      in String stichwort, in boolean positionAktualisieren);
    
  /**
   * Startet eine asynchrone Anfrage an den Remote Service zur
   * Abfrage der aktuellen Ortsposition. Der Rückgabewert wird
   * über einen Callback-Mechanismus an den Aufrufer 
   * zurückgeliefert.
   */
  oneway void getGpsDataAsynchron();
  
  /**
   * Registriert einen Callback beim Remote Service.
   */
  void registriereCallback(IServiceCallback callback);
  
  /**
   * Entfernt den Callback wieder aus dem Remote Service.
   */
  void entferneCallback(IServiceCallback callback);


}
